docs: Remove a reference to gtk_main_do_event

It is not great to put a function in the public api and
document it as "do not call this" only so we can refer
to its docs in other places. Therefore, fold the docs
directly into the input handling overview chapter.

diff --git a/docs/reference/gtk/input-handling.xml b/docs/reference/gtk/input-handling.xml
index f81252dfbb35f405a44474289d49f449a1e5386b..f419cd30f25995fd8adacefe9fc2cd9a65f60de1 100644 (file)
--- a/docs/reference/gtk/input-handling.xml
+++ b/docs/reference/gtk/input-handling.xml
@@ -92,12 +92,50 @@
 
     <para>
       The function which initially receives input events on the GTK
-      side is gtk_main_do_event(). See its documentation
-      for details of what it does: compression of enter/leave events,
-      identification of the widget receiving the event, pushing the event onto a
-      stack for gtk_get_current_event(), and propagating the event to the
-      widget.
-    </para>
+      side is responsible for a number of tasks.
+    </para>
+    <orderedlist>
+      <listitem><para>
+        Compress enter/leave notify events. If the event passed build an
+        enter/leave pair together with the next event (peeked from GDK), both
+        events are thrown away. This is to avoid a backlog of (de-)highlighting
+        widgets crossed by the pointer.
+      </para></listitem>
+      <listitem><para>
+        Find the widget which got the event. If the widget can’t be determined
+        the event is thrown away unless it belongs to a INCR transaction.
+      </para></listitem>
+      <listitem><para>
+        Then the event is pushed onto a stack so you can query the currently
+        handled event with gtk_get_current_event().
+      </para></listitem>
+      <listitem><para>
+        The event is sent to a widget. If a grab is active all events for widgets
+        that are not in the contained in the grab widget are sent to the latter
+        with a few exceptions:
+        <itemizedlist>
+          <listitem><para>
+            Deletion and destruction events are still sent to the event widget for
+            obvious reasons.
+          </para></listitem>
+          <listitem><para>
+            Events which directly relate to the visual representation of the event
+            widget.
+          </para></listitem>
+          <listitem><para>
+            Leave events are delivered to the event widget if there was an enter
+            event delivered to it before without the paired leave event.
+          </para></listitem>
+          <listitem><para>
+            Drag events are not redirected because it is unclear what the semantics
+            of that would be.
+          </para></listitem>
+        </itemizedlist>
+      </para></listitem>
+      <listitem><para>
+        After finishing the delivery the event is popped from the event stack.
+      </para></listitem>
+    </orderedlist>
 
     <para>
       When a GDK backend produces an input event, it is tied to a #GdkDevice and